<!doctype html public "-//w3c//dtd html 4.0 transitional//en">
<html>
<head>
   <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
   <title>Working with mod_jk</title>
<!-- $Id  $ -->
<!--
   Copyright 2001-2004 The Apache Software Foundation
 
   Licensed under the Apache License, Version 2.0 (the "License");
   you may not use this file except in compliance with the License.
   You may obtain a copy of the License at
 
       http://www.apache.org/licenses/LICENSE-2.0
 
   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.
-->
<link rel="stylesheet" href="style.css">
<style type="text/css">
    .inlinetd {
        background-color: #E0E0E0;
        vertical-align: text-top;
        border-top: thick black;
        border-right: thick black;
        border-bottom: thick black;
        border-left: thick black;
    }
    .inlineth {
        background-color: #d0d0d0;
        border-top: thick black;
        border-right: thick black;
        border-bottom: thick black;
        border-left: thick black;
    }
    .inlinetable {
        width: 75%;
        border: thick;
        background-color: #000000;
    }
    .subsection { margin:20pt; }
    .note { margin:20pt; padding:5pt; background-color:#e0e0ff; }

    </style>
</head>
<body>
<!-- Banner element, all hail the Project! -->
<table BORDER=0 CELLSPACING=0 CELLPADDING=0 WIDTH="100%" >
<tr>
<td ALIGN=LEFT WIDTH="50%"><a href="http://jakarta.apache.org/index.html"><img SRC="images/banner.gif" ALT="The Jakarta Project" BORDER=0 height=48 width=505></a></td>

<td ALIGN=RIGHT WIDTH="50%"><img SRC="images/tomcat.gif" ALT="The mighty Tomcat - Meow!" BORDER=0 height=71 width=100></td>
</tr>
</table>

<h1>
Working with mod_jk</h1>
By Gal Shachor <tt>&lt;<a href="mailto:shachor@il.ibm.com">shachor@il.ibm.com</a>&gt;</tt>
<h2>
Table of Contents</h2>

<ul>
<li>
<a href="#s2">What is mod_jk?</a></li>

<li>
<a href="#s3">Why mod_jk?</a></li>

<li>
<a href="#s4">What does it mean to me?</a></li>

<li>
<a href="#s5">Definitions and Terminology</a></li>

<li>
<a href="#s6">Obtaining mod_jk</a>

<ul>
<li>
<a href="#s61">mod_jk Binaries</a></li>

<li>
<a href="#s62">Building mod_jk</a></li>

<li>
<a href="#s63">Building mod_jk for NT</a></li>

<li>
<a href="#s64">Building mod_jk for Unix</a></li>
</ul></li>

<li>
<a href="#s7">Configuring Apache</a>

<ul>
<li>
<a href="#s71">Removing mod_jserv directives</a></li>

<li>
<a href="#s72">Configuring Apache to use mod_jk</a></li>

<li>
<a href="#s73">Assigning URLs to be redirected to Tomcat</a></li>
</ul></li>

<li>
<a href="#s8">Configuring Tomcat</a>

<ul>
<li>
<a href="#s81">Enabling Tomcat's Apache Auto-Config</a></li>

<li>
<a href="#s82">Configuring Tomcat to use the AJPv13 Protocol</a></li>

<li>
<a href="#s83">Defining Workers</a></li>
</ul></li>

<li>
<a href="#s9">Example Configuration</a></li>

<li>
<a href="#s10">Troubleshooting and F.A.Q's</a></li>

<li>
<a href="#s11">Credits</a></li>
</ul>

<hr>
<h2>
<a NAME="s2"></a>What is mod_jk?</h2>
mod_jk is a replacement to the elderly mod_jserv. It is a completely new
Tomcat-Apache plug-in that handles the communication between Tomcat and
Apache.
<br>
<hr>
<h2>
<a NAME="s3"></a>Why mod_jk?</h2>
Several reasons:
<ul>
<li>
<b>mod_jserv was too complex</b>. Because it was ported from Apache/JServ,
it brought with it lots of JServ specific bits that aren't needed by Apache.</li>

<li>
<b>mod_jserv supported only Apache</b>. Tomcat supports many web servers
through a compatibility layer named the jk library. Supporting two different
modes of work became problematic in terms of support, documentation and
bug fixes. mod_jk should fix that.</li>

<li>
The layered approach provided by the jk library makes it easier to support
both <b>Apache1.3.x <i>and</i> Apache2.xx.</b></li>

<li>
<b>Better support for SSL</b>. mod_jserv couldn't reliably identify whether
a request was made via HTTP or HTTPS. mod_jk can, using the newer Ajpv13
protocol.</li>
</ul>

<hr>
<h2>
<a NAME="s4"></a>What does it mean to me?</h2>
You will need to get to know a new simplified configuration mechanism.
The advantage is that learning this mechanism will give you a head start
if you want to deploy Tomcat on Apache and other web servers, such as Microsoft's
Internet Information Server (IIS) and the iPlanet Enterprise Web Server.
<br>
<hr>
<h2>
<a NAME="s5"></a>Definitions and Terminology</h2>
In this document I am going to use a few terms, so let's define them:
<br>&nbsp;
<table class="inlinetable" >
<tr>
<th class="inlineth">Term</th>

<th class="inlineth">Meaning</th>
</tr>

<tr>
<td class="inlinetd">Worker Process</td>

<td class="inlinetd">A worker is a tomcat instance that is running to serve
servlet requests coming from the web server. In most cases there is only
a single worker (the one and only tomcat process) but sometimes you will
run multiple workers to achieve load balancing or site partitioning. Each
worker is identified to the web server by the host were it is located,
the port where it listens and the communication protocol used to exchange
messages.</td>
</tr>

<tr>
<td class="inlinetd">In-Process Worker</td>

<td class="inlinetd">This is a special worker. Instead of working with
a Tomcat process residing on another process, the web server opens a JVM
and executes Tomcat inside the web server process address space. Our discussion
in this document is not going to get into this special worker.</td>
</tr>

<tr>
<td class="inlinetd">Web Server Plug-in/Tomcat Redirector</td>

<td class="inlinetd">For Tomcat to cooperate with any web server it needs
an &quot;agent&quot; to reside in the web server and send him servlet requests. This
is the web server plug-in, and in our case the web server plug-in is mod_jk.
The redirector usually comes in the shape of a DLL or shared object module
that you plug into the web server.</td>
</tr>

<tr>
<td class="inlinetd">Plug-in Configuration</td>

<td class="inlinetd">We need to configure the web server plug-in so that
it knows where the different Tomcat workers are and to which of them it
should forward requests. This information, accompanied with some internal
parameter, such as the log level, comprises the plug-in configuration.&nbsp;</td>
</tr>

<tr>
<td class="inlinetd">Web Server Configuration</td>

<td class="inlinetd">Each web server has some configuration that defines
its behavior, e.g. on which port to listen, what files to serve, what web
server plug-ins to load, etc. You will need to modify your web server configuration
to instruct it to load the Tomcat redirector mod_jk.</td>
</tr>
</table>

<hr>
<h2>
<a NAME="s6"></a>Obtaining mod_jk</h2>
mod_jk can be obtained in two formats - binary and source.&nbsp; Depending
on the platform you are running your web server on, a binary version of
mod_jk may be available.&nbsp; It is recommended to use the binary version
if one is available.&nbsp; If the binary is not available, follow the instructions
for building mod_jk from source.&nbsp; Notes at the end of this section
offer recommendations for specific platforms.
<h3>
<a NAME="s61"></a>mod_jk Binaries</h3>
Binaries for mod_jk are available for several platforms in the same area
as the Tomcat Binary Release.&nbsp; The binaries are located in subdirectories
by platform.&nbsp; For some platforms, such as Windows, this is the typical
way of obtaining mod_jk since most Windows systems do not have C compilers.&nbsp;
For others, the binary distribution of mod_jk offers simpler installation.
<p>For example, the Tomcat 3.3 Release at
 <a href="http://jakarta.apache.org/builds/jakarta-tomcat/release/v3.3/bin/">
 http://jakarta.apache.org/builds/jakarta-tomcat/release/v3.3/bin/</a>
contains the following:
<br>&nbsp;</p>
<table BORDER CELLSPACING=0 CELLPADDING=2 WIDTH="600" bordercolor="#000000" >
<tr>
<td WIDTH="15%">linux/i386</td>

<td WIDTH="85%">Contains mod_jk.so for Apache 1.3 for the standard API
as well as EAPI and mod_jk.so for Apache 2.0</td>
</tr>

<tr>
<td WIDTH="15%">netware/i386</td>

<td WIDTH="85%">Contains the mod_jk.nlm and nsapi.nlm</td>
</tr>

<tr>
<td WIDTH="15%">win32/i386</td>

<td WIDTH="85%">Contains the mod_jk.dll for Windows as well as other useful
binaries.</td>
</tr>
</table>

<p>Check the site for the latest binaries.
<p>Note: The version of mod_jk is not dependent on the version of Tomcat.&nbsp;
The Tomcat 3.3 distribution of mod_jk will function correctly with other
3.x versions of Tomcat, such as Tomcat 3.2.1.
<h3>
<a NAME="s62"></a>Building mod_jk</h3>
mod_jk is available in source distribution for all Windows and most Unix
platforms.&nbsp; The source for mod_jk is included in the Binary Distribution
of Tomcat in the TOMCAT_HOME/native/mod_jk/ directory.&nbsp; This directory
is organized by Web Server name and version.&nbsp; Each directory contains
the source as well as the appropriate build scripts, make files, or project
files.
<h3>
<a NAME="s63"></a>Building mod_jk for NT</h3>
The redirector was developed using Visual C++ version 6.0, so having this
environment is a prerequisite if you want to perform a custom build.
<p>The steps that you need to take are:
<ol>
<li>
Change directory to the apache1.3 or apache2.0 source directory depending
on your version of Apache.</li>

<li>
Set an APACHE1_HOME environment variable which points to where your Apache
is installed.</li>

<li>
Execute the following command:</li>

<p><br><span><tt>MSDEV mod_jk.dsp /MAKE ALL</tt></span>
<p>If msdev is not in your path, enter the full path to msdev.exe. Also,
ApacheCore.lib is expected to exist in the APACHE1_HOME\src\Debug or APACHE1_HOME\src\Release
(or the older APACHE1_HOME\src\CoreD or APACHE1_HOME\src\CoreR)
directories before linking will succeed. You will need to build enough
of the Apache source to create the required librarie(s).
<li>
Copy mod_jk.dll to Apache's modules directory.</li>
</ol>
This will build both release and debug versions of the redirector plug-in
(mod_jk).
<p>An alternative will be to open <tt>mod_jk.dsp</tt> in msdev and build
it using the build menu.
<h3>
<a NAME="s64"></a>Building mod_jk for Unix</h3>

<h4>
Apache</h4>

<ol>
<li>
Make sure your Apache has DSO support. You can check this with <tt>$APACHE_HOME/bin/httpd
-l</tt>. If you see &quot;mod_so.c&quot; in the output, DSO support is available.
If it's missing, you may have to recompile or reinstall Apache.</li>

<li>
Find out whether your Apache has EAPI support. If you compiled it yourself
from source, EAPI is probably not compiled in, unless you added it yourself
(perhaps with mod_ssl). You need to build mod_jk.so with or without EAPI
to match your Apache configuration. If you install a mismatched mod_jk.so,
<tt>$APACHE_HOME/bin/apachectl configtest</tt> will warn you.</li>

<li>
Make sure you have Perl 5 installed. The <tt>apxs</tt> script used to build
the module is written in Perl.</li>

<li>
Change directory to <tt>TOMCAT_HOME/native/mod_jk/apache1.3</tt> (or <tt>apache2.0</tt>).</li>

<p><br>Build mod_jk.so. Following are three techniques you can try, in
order of simplicity:
<ol>
<li>
Run the build script for your platform.&nbsp; If a build script is not
available for your platform, you may be able to build mod_jk using <tt>./build-unix.sh</tt>.
This script will set some variables, call <tt>apxs</tt> as below, and try
to copy mod_jk.so to $APACHE_HOME/libexec. If it fails, you need to do
the following manually:</li>

<ul>
<li>
set JAVA_HOME in your shell, e.g. &quot;<tt>set JAVA_HOME=/usr/local/jdk1.3.1;
export JAVA_HOME</tt>&quot;</li>

<li>
set APACHE_HOME in your shell, e.g. &quot;<tt>set APACHE_HOME=/usr/local/apache;
export APACHE_HOME</tt>&quot;</li>

<li>
uncomment the following line in the <tt>build-unix.sh</tt> file, replacing
&quot;linux&quot; with the name of your platform as specified in the Java include
directory for your installation</li>

<blockquote><tt># JAVA_INCLUDE=&quot;-I ${JAVA_HOME}/include -I ${JAVA_HOME}/include/linux&quot;</tt></blockquote>
</ul>

<li>
If build-unix.sh fails, you may have better luck with the Makefiles in
the same directory, e.g. &quot;<tt>make -f Makefile.linux mod_jk.so</tt>&quot;</li>

<p><br>Finally, you can try to build it manually. Run the <tt>apxs</tt>
command that came with your apache distribution (hint: look in /usr/local/apache/bin,
/usr/sbin, or wherever you installed apache). Type the command all on one
line.
<br>
<hr>
<p>For Linux:
<blockquote><tt>apxs -o mod_jk.so -I../jk -I/usr/local/jdk/include -I/usr/local/jdk/include/linux
-c *.c ../jk/*.c</tt></blockquote>
Your build may fail because the object files from the <tt>../jk</tt> directory
have been compiled to the current directory, rather than their source directory.
Running <tt>gcc -shared -o mod_jk.so *.o</tt> should finish the build.
<br>
<hr>
<p>For Solaris:
<p>Use the <tt>build-solaris.sh</tt> script as follows:
<blockquote><tt># sh build-solaris.sh</tt></blockquote>
This will build and install mod_jk.so in your apache/libexec directory.&nbsp;
This script contains settings for your Java and Apache home locations.&nbsp;
Make sure that these are set according to your installation.&nbsp; The
default settings are <tt>JAVA_HOME=/usr/java</tt> and <tt>APACHE_HOME=/usr/local/apache</tt>.&nbsp;
If your installation is different, you will need to edit the <tt>build-solaris.sh</tt>
script and change these values appropriately.
<p>See <tt>README.solaris</tt> located in <tt>TOMCAT_HOME/native/mod_jk/apache1.3</tt>
for more information.
<p>If the build script does not work, you can also build mod_jk as follows:
<blockquote><tt>$APACHE_HOME/bin/apxs -o mod_jk.so -DSOLARIS -I../jk -I/usr/java/include
-I/usr/java/include/solaris -c *.c ../jk/*.c</tt></blockquote>

<hr>
<p>For HP-UX 11.00:
<p>Use the <tt>build-hpux.sh</tt> script as follows:
<blockquote><tt># sh build-hpux.sh</tt></blockquote>
This will build and install mod_jk.so in your apache/libexec directory.&nbsp;
This script contains settings for your Java and Apache home locations.&nbsp;
Make sure that these are set according to your installation.&nbsp; The
default settings are <tt>JAVA_HOME=/opt/java1.3</tt> and <tt>APACHE_HOME=/usr/local/apache</tt>.&nbsp;
If your installation is different, you will need to edit the <tt>build-hpux.sh</tt>
script and change these values appropriately.
<p>Also note that there are two HP-UX build scripts.&nbsp; One script was
written to build mod_jk without JNI support using GNU GCC.&nbsp; The other
script builds mod_jk with JNI support, however, this script requires the
HP ANSI C Compiler (not the stripped down C compiler included with HP-UX
to rebuild the kernel).&nbsp; The HP Compiler is required because the dlopen()
and related shared libraries are only available for 64-bit applications
and reliable 64-bit compilation is not available with the current version
of GCC.
<p>The <tt>build-hpux.sh</tt> script should also work for HP-UX 10.00.
<p>See <tt>README.hpux</tt> located in <tt>TOMCAT_HOME/native/mod_jk/apache1.3</tt>
for more information.
<br>
<hr>
<p>For other Unixes (including FreeBSD):
<p>The <tt>build-hpux-cc.sh</tt> script should be modifiable for IRIX and
AIX.&nbsp; Edit the script and change the APACHE_HOME and JAVA_HOME locations
as required.
<br>
<hr>
<p>If you are using EAPI, try adding <tt>-DEAPI</tt> to the apxs command
after <tt>mod_jk.so</tt>.
<p>If apxs fails with <tt>apxs:Break: Command failed with rc=255</tt>,
it may have been damaged by mod_ssl. Search for:
<pre>my $CFG_LD_SHLIB&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; = q();&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; # substituted via Makefile.tmpl
my $CFG_LDFLAGS_SHLIB = q(); # substituted via Makefile.tmpl</pre>
and change to:
<pre>my $CFG_LD_SHLIB&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; = q(ld);&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; # substituted via Makefile.tmpl
my $CFG_LDFLAGS_SHLIB = q(-G); # substituted via Makefile.tmpl</pre>
If you've installed Java in another directory, adjust accordingly.
<p>For other Unixes you should be able to work it out, but remember that
<b>the order of the arguments to <tt>apxs</tt> is important!</b>.</ol>

<li>
Now, copy the mod_jk library.&nbsp; <tt># cp mod_jk.so $APACHE_HOME/libexec</tt>.
(Note that the build scripts attempt to do this, but you may have to <tt>su</tt>
first.)</li>
</ol>

<h4>
Other Webservers</h4>
There are several Makefiles in the other directories under the <tt>TOMCAT_HOME/native/mod_jk/</tt>
directory.&nbsp; You should also check the Tomcat documentation for specific
information related to other web servers.
<br>
<hr>
<h2>
<a NAME="s7"></a>Configuring Apache</h2>
This section details the configuration that is required for the Apache
Web Server to support mod_jk.
<h3>
<a NAME="s71"></a>Removing mod_jserv directives</h3>

<div class="subsection">If you've previously configured Apache to use mod_jserv,
remove any <tt>ApJServMount</tt> directives from your httpd.conf. If you're
including <tt>tomcat-apache.conf</tt> or <tt>tomcat.conf</tt>, you'll want
to remove them as well - they are specific to mod_jserv.&nbsp; The mod_jserv
configuration directives are not compatible with mod_jk!</div>

<h3>
<a NAME="s72"></a>Configure Apache to use mod_jk</h3>

<div class=subsection>The simplest way to configure Apache to use mod_jk
is to use Tomcat to generate the mod_jk configuration file and put the following
include directive at the end of your Apache httpd.conf file (make sure
you replace TOMCAT_HOME with the correct path for your Tomcat installation:
<p><tt>Include TOMCAT_HOME/conf/auto/mod_jk.conf</tt>
<p>Example:
<p><tt>Include /usr/local/jakarta-tomcat/conf/auto/mod_jk.conf</tt>
<p>This will tell Apache to use directives in the mod_jk.conf file
in the Apache configuration.&nbsp; This file is created by starting Tomcat
with the &quot;jkconf&quot; option.  Tomcat will initialize, write the 
configuration file and then exit. This may be done while an instance of Tomcat
is running.  Options for controlling how the mod_jk configuration file is
generated are described in the configuring Tomcat section
below [<a href="#s8">Configuring Tomcat</a>].
<p><b>NOTE:&nbsp; If you plan to use the Tomcat generated configuration,
skip the rest of this section and continue with the <a href="#s8">Configuring
Tomcat</a> section.</b>
<p>Custom configurations can be created by enabling the auto-configuration
and copying the <tt>TOMCAT_HOME/conf/auto/mod_jk.conf</tt> file to your
own configuration file, such as <tt>TOMCAT_HOME/conf/jk/mod_jk.conf</tt>.
<p>The basic configuration is as follows:
<ul>
<li>
You will need to instruct Apache to load Tomcat. This can be done with
Apache's <tt>LoadModule</tt> and <tt>AddModule</tt> configuration directives.</li>

<li>
You must inform mod_jk the location of your <tt>workers.properties</tt>
file. Use mod_jk's <tt>JkWorkersFile</tt> configuration directive.</li>

<li>
You should specify a location where mod_jk is going to place its log file
and a log level to be used. Use the <tt>JkLogFile</tt> and <tt>JkLogLevel</tt>
configuration directives. Possible log levels are <i>debug</i>, <i>info</i>,
<i>error</i> and <i>emerg</i>.  If the JkLogLevel is not specified,
no log is generated.</li>

<li>
The directive <tt>JkLogStampFormat</tt> will configure the date/time format
found on mod_jk logfile. Using <tt>strftime()</tt> format string it's set
by default to &quot;[%a %b %d %H:%M:%S %Y] &quot;</li>
</ul>
A simple example would be to include the following lines in your <tt>httpd.conf</tt>
file:
<blockquote>
<pre>LoadModule&nbsp;&nbsp;&nbsp; jk_module&nbsp; libexec/mod_jk.so
AddModule&nbsp;&nbsp;&nbsp;&nbsp; mod_jk.c
JkWorkersFile /usr/local/jakarta-tomcat/conf/workers.properties
JkLogFile&nbsp;&nbsp;&nbsp;&nbsp; /usr/local/apache/logs/mod_jk.log
JkLogLevel&nbsp;&nbsp;&nbsp; info
JkLogStampFormat &quot;[%a %b %d %H:%M:%S %Y] &quot;</pre>
</blockquote>
</div>

<h3>
<a NAME="s73"></a>Assigning URLs to Tomcat</h3>

<div class=subsection>If you have created a custom or local version of
<tt>mod_jk.conf</tt> as noted above, you can change settings such
as the workers or URL prefix.
<p>Use mod_jk's JkMount directive to assign specific URLs to Tomcat. In
general the structure of a JkMount directive is:
<pre>JkMount <i>&lt;URL prefix&gt;</i> <i>&lt;Worker name></i></pre>
For example the following directives will send all requests ending in
<tt>.jsp</tt>
or beginning with <tt>/servlet</tt> to the &quot;<tt>ajp13</tt>&quot; worker, but
jsp requests to files located in /otherworker will go to &quot;<tt>remoteworker</tt>&quot;.
<blockquote>
<pre>JkMount /*.jsp ajp13
JkMount /servlet/* ajp13
JkMount /otherworker/*.jsp remoteworker</pre>
</blockquote>
You can use the <tt>JkMount</tt> directive at the top level or inside <tt>&lt;VirtualHost&gt;</tt>
sections of your httpd.conf file.</div>

<hr>
<h2>
<a NAME="s8"></a>Configuring Tomcat</h2>

<h3>
<a NAME="s81"></a>Enabling Tomcat's Apache Auto-Config</h3>

<div class=subsection>In most simple cases Tomcat can generate the needed
Apache configuration. The default installation of Tomcat comes configured to
generate a configuration file on demand for Apache to use mod_jk.
Most of the time you don't need to do anything but include this file (appending
<tt>&quot;Include TOMCAT_HOME/conf/auto/mod_jk.conf&quot;</tt>) in your httpd.conf,
as shown in the previous section (<a href="#s7">Configuring Apache</a>).

<p>To have Tomcat generate the configuration file, start Tomcat with the
&quot;jkconf&quot; option. Tomcat will initialize, write the configuration
file, and then exit. This may be done while an instance of Tomcat is running.</p>

<p>The generation of the mod_jk configuration file is controlled by the
<a href="serverxml.html#ApacheConfig">ApacheConfig</a> module. The default
installation of Tomcat 3.3 comes with the ApacheConfig directive already
present in the <tt>TOMCAT_HOME/conf/server.xml</tt>.</p>

<p><b>Note:</b> Generating the mod_jk configuration file on demand is new in Tomcat 3.3.&nbsp;
Older versions of Tomcat create the auto-config file without a directive
in server.xml and generate it each time Tomcat is started.&nbsp;
The new ApacheConfig directive in Tomcat 3.3 allows for additional
configuration options as detailed later in this section.&nbsp; For older
versions of Tomcat, refer to the documentation that came with that version.
<p>If you have special needs, for example mounting URL prefixes that are
not the default, you can use this file as a base for your customized configuration
and save the results in another file. If you manage the Apache configuration
yourself you'll need to update it whenever you add a new context.
<p>Note that you must restart tomcat and apache after adding a new context;
Apache doesn't support configuration changes without a restart. Also the
file <tt>TOMCAT_HOME/conf/auto/mod_jk.conf</tt> is generated when tomcat
starts, so you'll need to start Tomcat before Apache. Tomcat will overwrite
<tt>TOMCAT_HOME/conf/auto/mod_jk.conf</tt> each startup so customized
configuration should be kept elsewhere.&nbsp; For example, copy 
<tt>TOMCAT_HOME/conf/auto/mod_jk.conf</tt>
to <tt>TOMCAT_HOME/conf/jk/mod_jk.conf
</tt>before making changes.&nbsp;
You'll need to start Tomcat with the &quot;jkconf&quot; option once to generate
this file with your configuration for the first time.
<p>It is also possible to specify the location of the auto generated files
by setting options in the &lt;ApacheConfig /&gt; block.&nbsp; The following
details the syntax:
<blockquote>
<pre>&lt; ContextManager ... &gt;
&nbsp; ...
&nbsp; &lt;ApacheConfig <i>options</i> /&gt;
&nbsp; ...
&lt; /ContextManager &gt;</pre>
</blockquote>
&nbsp;where <i>options</i> can include any of the following attributes:
<ul>
<li><b>configHome</b> - default parent directory for the following paths.
    If not set, this defaults to TOMCAT_HOME. Ignored
    whenever any of the following paths is absolute.</li>
<li><b>jkConfig</b> - path to use for writing Apache mod_jk conf file. If
    not set, defaults to &quot;conf/auto/mod_jk.conf&quot;.</li>
<li><b>workersConfig</b> - path to workers.properties file used by 
    mod_jk. If not set, defaults to &quot;conf/jk/workers.properties&quot;.</li>
<li><b>modJk</b> - path to Apache mod_jk plug-in file.  If not set,
    defaults to &quot;modules/mod_jk.dll&quot; on windows,
    &quot;modules/mod_jk.nlm&quot; on netware, and
    &quot;libexec/mod_jk.so&quot; everywhere else.</li>
<li><b>jkLog</b> - path to log file to be used by mod_jk.</li>
<li><b>jkDebug</b> - JK Loglevel setting.  May be debug, info, error, or emerg.
    If not set, defaults to no log.</li>
<li><b>jkWorker</b> The desired worker.  Must be set to one of the workers
    defined in the workers.properties file. &quot;ajp12&quot;, &quot;ajp13&quot;
    or &quot;inprocess&quot; are the workers found in the default
    workers.properties file. If not specified, defaults to &quot;ajp13&quot;
    if an Ajp13Connector is in use, otherwise it defaults to &quot;ajp12&quot;.</li>
<li><b>forwardAll</b> - If true, forward all requests to Tomcat.
    This helps ensure that all the behavior configured in the web.xml
    file functions correctly. If false, let Apache serve static resources.
    The default is true. Warning: When false, some configuration in
    the web.xml may not be duplicated in Apache.
    Review the mod_jk conf file to see what
    configuration is actually being set in Apache.</li>
<li><b>noRoot</b> - If true, the root context is not mapped to
    Tomcat.  If false and forwardAll is true, all requests
    to the root context are mapped to Tomcat. If false and
    forwardAll is false, only JSP and servlets requests to
    the root context are mapped to Tomcat. When false,
    to correctly serve Tomcat's root context you must also
    modify the DocumentRoot setting in Apache's httpd.conf
    file to point to Tomcat's root context directory.
    Otherwise some content, such as Apache's index.html,
    will be served by Apache before mod_jk gets a chance
    to claim the request and pass it to Tomcat.
    The default is true.</li>
</ul>
&nbsp;Example:
<blockquote>
<pre>...

&lt;ApacheConfig configHome=&quot;/home/mydir&quot; /&gt;

...</pre>
</blockquote>

<p><b>Note:</b> The default mod_jk configuration file generated by:
<blockquote>
<pre>&lt;ApacheConfig /&gt;</pre>
</blockquote>
differs from the file generated by Tomcat 3.2.x.  In Tomcat 3.3, the default
is to forward all requests to Tomcat for Tomcat's contexts (i.e.
forwardAll=&quot;true&quot;), excluding the root context.  This helps ensure
that behavior configured in web.xml files will function properly.
The configuration that best matches Tomcat 3.2.x behavior is:
<blockquote>
<pre>&lt;ApacheConfig forwardAll=&quot;false&quot; noRoot=&quot;false&quot;
        jkConfig=&quot;conf/mod_jk.conf-auto&quot; jkDebug=&quot;error&quot; /&gt;</pre>
</blockquote>
With this configuration, JSP and servlet requests to the root context
will be served from Tomcat's ROOT webapp.  Other requests, such as for static
files, will be served from Apache's DocumentRoot directory.  If Apache's
DocumentRoot isn't updated to point to Tomcat's ROOT webapp, then the
root context will malfunction.  For example, JSP's that reference &quot;.gif&quot;
files in Tomcat's ROOT webapp will not be able to display them since
they won't be found under Apache's DocumentRoot directory.</p>
</div>

<h3>
<a NAME="s82"></a>(Optional) Configuring Tomcat to use the Ajpv13 protocol</h3>

<div class=subsection>mod_jk can use either the original Ajpv12 protocol
or the newer Ajpv13 protocol. Both protocols are enabled by default. The
&quot;Ajp13&quot; Connection Handler in Tomcat will give you the benefit of a faster
protocol and the ability to identify requests made via HTTPS.
<p>The default installation of Tomcat 3.3 comes with connectors for both
protocols in the <tt>TOMCAT_HOME/conf/server.xml</tt>.  The default choice by
the ApacheConfig directive will be to using the &quot;ajp13&quot; worker which
uses the Ajpv13 protocol. Even though mod_jk uses the Ajpv13 by default, you
shouldn't remove the Ajpv12 connector present in the <tt>server.xml</tt> file.
The Ajpv12 connector is also used for shutting down Tomcat.</div>

<h3>
<a NAME="s83"></a>(Optional) Defining &quot;workers&quot;</h3>

<h4>
Configuring workers manually.</h4>

<div class=subsection>Workers are configured using the file <tt>TOMCAT_HOME/conf/jk/workers.properties</tt>.
There is a great deal of information in the
<a href="Tomcat-Workers-HowTo.html">workers.properties
howto</a> document, and you should really look at that first. If you're
in a hurry however, you can probably get away with editing the file <tt>workers.properties</tt>
and setting the <tt>workers.tomcat_home</tt>, <tt>workers.java_home</tt>
and <tt>ps</tt> variables to the correct values for your system.</div>

<hr>
<h2>
<a NAME="s9"></a>Example Configuration</h2>
Here's an example configuration which probably reflects many real-world
setups. A site is using Tomcat and Apache with two virtual hosts (one of
them using HTTPS as well, which we're assuming is being handled by mod_ssl).
<p>URLs ending in .jsp and beginning with /servlet are handled by Tomcat,
the rest are handled by Apache. The files for each Host are server out
of /web/host1 and /web/host2 respectively.
<p>The example are over-simplified and incomplete but should get you started.
Also note, this form virtual host setup is new in Tomcat 3.3 and later - <i>this example
won't work with Tomcat 3.2 and earlier.</i>.
<br>&nbsp;
<table class="inlinetable" >
<tr>
<td class="inlinetd">
<blockquote>
<pre>.
.
&lt;Ajp12Connector port=&quot;8007&quot; /&gt;

&lt;Ajp13Connector port=&quot;8009&quot; /&gt;
.</pre>
</blockquote>
</td>
</tr>
</table>
<i>Table 1 - Excerpt from server.xml showing the Ajp12 and Ajp13 Connectors.</i>
<br>&nbsp;
<table class="inlinetable" >
<tr>
<td class="inlinetd">
<blockquote>
<pre>
&lt;?xml version=&quot;1.0&quot; encoding=&quot;ISO-8859-1&quot;?&gt;
&lt;Server&gt;
    &lt;Host name=&quot;host1.apache.org&quot;&gt;
    &nbsp; &lt;Context path=&quot;&quot; docBase=&quot;/web/host1&quot; debug=&quot;0&quot;/&gt;
    &lt;/Host&gt;
    &lt;Host name=&quot;host2.apache.org&quot;&gt;
    &nbsp; &lt;Context path=&quot;&quot; docBase=&quot;/web/host2&quot; debug=&quot;0&quot;/&gt;
    &lt;/Host&gt;
&lt;/Server&gt;
</pre>
</blockquote>
</td>
</tr>
</table>
<i>Table 2 - Apps-vhosts.xml file showing two virtual hosts, each with a default
context defined.</i>
<br>&nbsp;
<table class="inlinetable" >
<tr>
<td class="inlinetd">
<blockquote>
<pre># Setup for Solaris system
#
workers.tomcat_home=/usr/local/jakarta-tomcat
workers.java_home=/usr/java
ps=/
worker.list=ajp12, ajp13

# Definition for Ajp13 worker (Ajp12 left to readers imagination)
#
worker.ajp13.port=8009
worker.ajp13.host=localhost
worker.ajp13.type=ajp13</pre>
</blockquote>
</td>
</tr>
</table>
<i>Table 3 - Excerpt from workers.properties showing the Ajp13 worker</i>
<br>&nbsp;
<table class="inlinetable" >
<tr>
<td class="inlinetd">
<blockquote>
<pre># Load mod_jk
#
LoadModule&nbsp;&nbsp;&nbsp; jk_module&nbsp; libexec/mod_jk.so
AddModule&nbsp;&nbsp;&nbsp;&nbsp; mod_jk.c

# Configure mod_jk
#
JkWorkersFile /usr/local/jakarta-tomcat/conf/jk/workers.properties
JkLogFile&nbsp;&nbsp;&nbsp;&nbsp; /usr/local/apache/logs/mod_jk.log
JkLogLevel&nbsp;&nbsp;&nbsp; info

# First Virtual Host.
#
&lt;VirtualHost 10.0.0.1:80>
&nbsp; DocumentRoot /web/host1
&nbsp; ServerName host1.apache.org
&nbsp; JkMount /*.jsp ajp13
&nbsp; JkMount /servlet/* ajp13
&lt;/VirtualHost&gt;

# Second Virtual Host. Also accessible via HTTPS
#
&lt;VirtualHost 10.0.0.2:80&gt;
&nbsp; DocumentRoot /web/host2
&nbsp; ServerName host2.apache.org
&nbsp; JkMount /*.jsp ajp13
&nbsp; JkMount /servlet/* ajp13
&lt;/VirtualHost&gt;

&lt;VirtualHost 10.0.0.2:443&gt;
&nbsp; DocumentRoot /web/host2
&nbsp; ServerName host2.apache.org
&nbsp; SSLEngine On
&nbsp; JkMount /*.jsp ajp13
&nbsp; JkMount /servlet/* ajp13
&lt;/VirtualHost&gt;

</pre>
</blockquote>
</td>
</tr>
</table>
<i>Table 4 - Excerpt from Apaches httpd.conf showing JK directives.</i>
<hr>
<h2>
<a NAME="s10"></a>Troubleshooting and F.A.Q.s</h2>

<h3>
Q. Where can I get help/support for mod_jk?</h3>
A. The primary mechanism for support is through the Tomcat Documentation
included in the TOMCAT_HOME/doc directory.&nbsp; These documents are viewable
via browser through Tomcat <a href="http://localhost:8080/doc/index.html">http://localhost:8080/doc/index.html</a>.&nbsp;
Documentation is also available on the Apache Jakarta web site for Tomcat
at <a href="http://jakarta.apache.org/tomcat/tomcat-3.3-doc/index.html">http://jakarta.apache.org/tomcat/tomcat-3.3-doc/index.html</a>.
<p>For additional help, the best resource is the Tomcat Users Discussion
list.&nbsp; You should start by searching the mail list archives located
at <a href="http://www.mail-archive.com/tomcat-user@jakarta.apache.org/">http://www.mail-archive.com/tomcat-user@jakarta.apache.org/</a>
or <a href="http://mikal.org/interests/java/tomcat/index.jsp">http://mikal.org/interests/java/tomcat/index.jsp</a>
before you post questions to the list.&nbsp; If you are unable to locate
the answer to your question in the archive, you can post questions about
Tomcat or mod_jk to the user list for assistance.&nbsp; Make sure that
you include the version of Apache and Tomcat that you are using as well
as the platform you are running on. <a href="http://jakarta.apache.org/site/mail.html">http://jakarta.apache.org/site/mail.html</a>
<h3>
Q. I can't find mod_jk anywhere. Where is it?</h3>
A. Starting with Tomcat 3.3, the source for mod_jk is included with the
binary distribution, in the native/mod_jk
directory.&nbsp; You can also download the Source Distribution of Tomcat
to obtain the source for mod_jk, which is how it was obtained in versions
prior to Tomcat 3.3. The Binary Distributions of mod_jk are available at
the same location as the Binary Distribution of Tomcat.&nbsp; The mod_jk
binaries are located in subdirectories by platform. But in May 2001, the
jakarta-tomcat-connectors was started and you'll find here up to date featured
mod_jk (ie: new protocols AJP14/WARP)
<h3>
Q. Which protocol should I use? Ajp12 or Ajp13?</h3>
A. Ajp13 is a newer protocol, it's faster, and it works better with SSL.
You almost certainly want to use it. There is more information in the
<a href="Tomcat-Workers-HowTo.html">workers.properties
howto</a> document.
<h3>
Q. Whenever I restart Tomcat, Apache locks up!</h3>
A. The Ajp13 protocol keeps an open socket between Tomcat and Apache. The
latest release of mod_jk (the one found since Tomcat 3.3-m2 and J-T-C)
handle the network failure. But with previous release of mod_jk, you may
have to restart Apache as well.
<h3>
Q. Why do two mod_jk.so files exist (-eapi ad -noeapi) in download dir
for Linux ?</h3>
A. Many versions of Apache use a modified API, known at Extended API.
For example, Apache using mod_ssl and the Apache present in certain recent
Linux distributions. So if you have an 'Extended Apache', you need to
use mod_jk.so-eapi, and use mod_jk.so-noeapi for standard Apache. It's wise
to avoid using EAPI modules on standard API Apache and standard API modules
on EAPI Apache. Always be sure to have the mod_jk.so for your version
of Apache.
<h3>
Q. What's that message about 'garbled DSO ?'</h3>
A. It's related to Apache EAPI. The message 'mod_jk.so is garbled - perhaps
this is not an Apache module DSO ?' just told you are trying to install
a mod_jk.so DSO module that was compiled on an Apache using EAPI, such as
Apache-mod_ssl or Apache from Redhat distro 6.2/7.0. However, your system is using
the standard Apache with the normal API.
<h3>
Q. And the message about 'module might crash under EAPI! '</h3>
A. Also related to EAPI, the message '[warn] Loaded DSO /usr/lib/apache/mod_jk.so
uses plain Apache 1.3 API, this module might crash under EAPI! (please
recompile it with -DEAPI)', the mod_jk.so was compiled under normal Apache
with standard API and you are trying to install the module on an Apache using
EAPI.
<h3>
Q. Where can I get more information?</h3>
A. The <a href="Tomcat-Workers-HowTo.html">workers.properties howto</a>
document has considerably more in-depth information than this one, and
is worth a look. You could also try searching the mailing list archives
for &quot;mod_jk&quot; or look at the source.
<h3>
Q. APXS is getting an error during the build of mod_jk, like rc=0 or rc=255.&nbsp;
I tried all of the steps in the build section, what do I do now?</h3>
A. APXS is a Perl script that is created when you build the Apache web
server from source.&nbsp; Chances are that if you are getting these errors
and you obtained Apache as a binary distribution, that APXS is not configured
correctly for your system.&nbsp; Your best bet is to get the Apache source
from <a href="http://httpd.apache.org">http://httpd.apache.org</a> and
build it yourself.&nbsp; Use the following for a basic build (read the
Apache docs for other options):
<blockquote>
<pre># cd /usr/local/src
# gzip -dc apache_1.3.19.tar.gz|tar xvf -
# cd apache_1.3.19
# ./configure --prefix=/usr/local/apache \
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; --enable-module=most \
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; --enable-shared=max
# make
# make install</pre>
</blockquote>
Note: The above steps assume that you downloaded the Apache source and
placed it in your /usr/local/src directory.
<h3>
Q. Why doesn't my form authentication work? I'm getting similar error messages
from Apache:</h3>

<table class="inlinetable"><tr><td class="inlinetd">
<blockquote><pre>Not Found
The requested URL /login/j_security_check was not found on this server.
</pre></blockquote>
</td></tr></table>

A. If you used manual configuration such as:

<table class="inlinetable"><tr><td class="inlinetd">
<blockquote><pre>
JkMount /*.jsp ajp13
</pre></blockquote>
</td></tr></table>

or

<table class="inlinetable"><tr><td class="inlinetd">
<blockquote><pre>
JkMount /*.vm ajp13
</pre></blockquote>
</td></tr></table>

mod_jk will pass requests for all JSP or Velocity pages to Tomcat. If form
authentication is configured like this:

<table class="inlinetable"><tr><td class="inlinetd">
<blockquote><pre>
&lt;login-config&gt;
  &lt;auth-method&gt;FORM&lt;/auth-method&gt;
  &lt;realm-name&gt;Protected&lt;/realm-name&gt;
  &lt;form-login-config&gt;
    &lt;form-login-page&gt;/login/login.vm&lt;/form-login-page&gt;
    &lt;form-error-page&gt;/login/error.vm&lt;/form-error-page&gt;
  &lt;/form-login-config&gt;
&lt;/login-config&gt;
</pre></blockquote>
</td></tr></table>

then there is also another, somewhat hidden request involved in the
authentication process: <strong>/login/j_security_check</strong>. It is the
'action' of the form specified within <strong>login.vm</strong> and
<strong>error.vm</strong>, usually:

<table class="inlinetable"><tr><td class="inlinetd">
<blockquote><pre>
&lt;form method=&quot;post&quot; action=&quot;j_security_check&quot;&gt;
</pre></blockquote>
</td></tr></table>

The request <strong>/login/j_security_check</strong> is not mapped, therefore
mod_jk doesn't know that it should pass it to Tomcat. The following fixes the
problem:

<table class="inlinetable"><tr><td class="inlinetd">
<blockquote><pre>
JkMount /*.vm ajp13
JkMount /login/j_security_check ajp13
</pre></blockquote>
</td></tr></table>

<hr>

<h2>
<a NAME="s11"></a>Credits</h2>
This document was originally created by
<a href="mailto:shachor@il.ibm.com">Gal
Shachor</a>
<p>Revisions by (Alphabetical)
<p>Mike Braden <tt>&lt;<a href="mailto:mikeb@mwbinc.com">mikeb@mwbinc.com</a>&gt;</tt>
<br>Mike Bremford
<br>Chris Pepper
<p>With help from countless others on the tomcat-dev and tomcat-user lists!
<br>&nbsp;
<table BORDER=0 CELLSPACING=0 CELLPADDING=10 WIDTH="100%" >
<tr>
<td>
<div class="fineprint">Copyright &copy;1999-2001 The Apache Software Foundation</div>

<br><a href="http://jakarta.apache.org/legal.html">Legal Stuff They Make
Us Say</a>
<br><a href="http://jakarta.apache.org/contact.html">Contact Information</a></td>
</tr>
</table>

</body>
</html>
